home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / old-compression / clOpenCompressor.z / clOpenCompressor
Encoding:
Text File  |  2002-10-03  |  11.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                        ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      clOpenCompressor, clCompress, clCloseCompressor - Compress a video or
  10.      audio stream
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ccccllll....hhhh>>>>
  14.  
  15.      iiiinnnntttt ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, CCCCLLLLhhhhaaaannnnddddlllleeee ****hhhhaaaannnnddddlllleeeePPPPttttrrrr))))
  16.      iiiinnnntttt ccccllllCCCCoooommmmpppprrrreeeessssssss((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt nnnnuuuummmmbbbbeeeerrrrOOOOffffFFFFrrrraaaammmmeeeessss,,,,
  17.          vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr,,,, iiiinnnntttt ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr))))
  18.      iiiinnnntttt ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee))))
  19.  
  20. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  21.      _s_c_h_e_m_e         The compression scheme to use.
  22.  
  23.      _h_a_n_d_l_e_P_t_r      A pointer to the returned handle of the compressor. Used
  24.                     by subsequent calls to identify the compressor.
  25.  
  26.      _h_a_n_d_l_e         A handle to the compressor.
  27.  
  28.      _n_u_m_b_e_r_O_f_F_r_a_m_e_s The number of frames to compress, which should be a
  29.                     multiple of CL_FRAMES_PER_CHUNK (usually 1 for video).
  30.                     _n_u_m_b_e_r_O_f_F_r_a_m_e_s may also be specified as
  31.                     CCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUOOOOUUUUSSSS____BBBBLLLLOOOOCCCCKKKK or CCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUOOOOUUUUSSSS____NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK.
  32.  
  33.      _f_r_a_m_e_B_u_f_f_e_r    A pointer to the frame buffer to be compressed. A value of
  34.                     CCCCLLLL____EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL____DDDDEEEEVVVVIIIICCCCEEEE may be used with some compressors to
  35.                     indicate a direct connection to an external video or audio
  36.                     source.  A value of NULL selects the use of a previously
  37.                     created buffer to supply the frame data (Implicit
  38.                     Buffering).
  39.  
  40.      _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r_S_i_z_e
  41.                     A pointer to the returned size of the compressed data in
  42.                     bytes.
  43.  
  44.      _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r
  45.                     A pointer to where the compressed data is to be placed. A
  46.                     value of NULL selects the use of a previously created
  47.                     buffer to place the compressed data (Implicit Buffering).
  48.  
  49. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  50.      ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr opens a compressor for a given scheme.  It is called
  51.      before ccccllllCCCCoooommmmpppprrrreeeessssssss or any call that requires a compressor handle.
  52.      ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr closes the compressor after which _h_a_n_d_l_e is no longer
  53.      valid.
  54.  
  55.      ccccllllCCCCoooommmmpppprrrreeeessssssss invokes different buffering models depending on the values of
  56.      the buffer arguments (see CLintro(3dm)).
  57.  
  58.      1. Direct Buffering
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                        ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.           If _f_r_a_m_e_B_u_f_f_e_r and _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r are non-NULL,
  75.           ccccllllCCCCoooommmmpppprrrreeeessssssss compresses _n_u_m_b_e_r_O_f_F_r_a_m_e_s from
  76.           _f_r_a_m_e_B_u_f_f_e_r and stores the result in _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r
  77.           and the resulting size in _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r_S_i_z_e.
  78.           _f_r_a_m_e_B_u_f_f_e_r may also be set to CL_EXTERNAL_DEVICE to indicate
  79.           a hardware input source (currently supported by CL_JPEG_COSMO).
  80.  
  81.      2. Implicit Buffering
  82.  
  83.           If _f_r_a_m_e_B_u_f_f_e_r and _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r are NULL,
  84.           ccccllllCCCCoooommmmpppprrrreeeessssssss operates on buffers that have been created
  85.           previously with ccccllllCCCCrrrreeeeaaaatttteeeeBBBBuuuuffff.  The input buffer should be
  86.           filled with calls to ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee, ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd, and
  87.           ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd.  The output buffer should be emptied
  88.           with calls to ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd and ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll.
  89.  
  90.      Direct and Implicit Buffering models may be mixed in one call by setting
  91.      one of the buffer arguments to be non-NULL, and the other to be NULL.
  92.  
  93.      With either model, buffers should be appropriately sized for proper
  94.      execution of ccccllllCCCCoooommmmpppprrrreeeessssssss.  The input frame buffer should have a minimum
  95.      capacity of CL_FRAMES_PER_CHUNK frames.  The output compressed buffer
  96.      should have a minimum capacity of CL_COMPRESSED_BUFFER_SIZE bytes.  These
  97.      parameters may be determined by calling ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmssss, after first calling
  98.      ccccllllSSSSeeeettttPPPPaaaarrrraaaammmmssss to provide the compressor with initialization information
  99.      such as input dimensions and format.
  100.  
  101.      If _n_u_m_b_e_r_O_f_F_r_a_m_e_s is non-negative, ccccllllCCCCoooommmmpppprrrreeeessssssss attempts to consume
  102.      _n_u_m_b_e_r_O_f_F_r_a_m_e_s frames of input data and may produce up to
  103.      CL_COMPRESSED_BUFFER_SIZE * _n_u_m_b_e_r_O_f_F_r_a_m_e_s / CL_FRAMES_PER_CHUNK bytes of
  104.      output data.  The call does not return until processing is completed.
  105.  
  106.      If _n_u_m_b_e_r_O_f_F_r_a_m_e_s is specified as CL_CONTINUOUS_BLOCK or
  107.      CL_CONTINUOUS_NONBLOCK then ccccllllCCCCoooommmmpppprrrreeeessssssss continues until either the input
  108.      buffer is marked done, or a call to ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr is made.
  109.      CL_CONTINUOUS_NONBLOCK differs from CL_CONTINUOUS_BLOCK in that the call
  110.      to ccccllllCCCCoooommmmpppprrrreeeessssssss returns immediately while the compression occurs in a
  111.      separate thread.  These special values should only be used with Implicit
  112.      Buffering.
  113.  
  114.      Multiple compressors can be open simultaneously.  _h_a_n_d_l_e identifies which
  115.      one is being referenced.
  116.  
  117.  
  118. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  119.      Upon success, ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr and ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr return SUCCESS, and
  120.      ccccllllCCCCoooommmmpppprrrreeeessssssss returns either the numberOfFrames actually consumed or, in the
  121.      case of CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.
  122.  
  123.      Upon failure, each routine returns a negative error code.  With some
  124.      schemes, ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr returns CL_SCHEME_BUSY if there is a system
  125.      resource (e.g. a piece of hardware) which is in use by another process.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                        ccccllll CCCCoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      A return code of CL_SCHEME_NOT_AVAILABLE indicates that the hardware or
  141.      software required by the scheme is not installed on the system.
  142.  
  143.  
  144.  
  145. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  146.           #include <dmedia/cl.h>
  147.  
  148.           int paramValueBuffer[][2] = {
  149.               CL_IMAGE_WIDTH,  0,
  150.               CL_IMAGE_HEIGHT, 0,
  151.               CL_COMPRESSED_BUFFER_SIZE, 0
  152.           };
  153.            ...
  154.           /* Open the compressor */
  155.           clOpenCompressor(CL_MVC1_SOFTWARE, &handle);
  156.  
  157.           /* Configure the compressor by setting some params */
  158.           paramValueBuffer[0][1] = 320;
  159.           paramValueBuffer[1][1] = 240;
  160.           clSetParams(handle, (int *)paramValueBuffer, 4);
  161.  
  162.           /* Allocate output buffer of the required size */
  163.           clGetParams(handle, (int *)paramValueBuffer, 6);
  164.           compressedBuffer = malloc(paramValueBuffer[2][1]);
  165.  
  166.           /* Compress a series of frames */
  167.           for(i = 0; i < N; i++)
  168.           {
  169.               /* Get a frame from somewhere */
  170.                ...
  171.               clCompress(handle, 1, frameBuffer, &compressedBufferSize,
  172.                compressedBuffer);
  173.               /* Write the compressed data to somewhere else */
  174.                ...
  175.           }
  176.  
  177.           /* Close the compressor */
  178.           clCloseCompressor(handle);
  179.  
  180.  
  181. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  182.      CLintro(3dm), clSetParams(3dm), clGetParams(3dm), clCreateBuf(3dm),
  183.      clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm), clUpdateTail(3dm)
  184.      clDoneUpdatingHead(3dm)
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.